.TH ADMIN.SH 1 LOCAL

.SH NAME
admin.sh - manage starting and stopping modules

.SH SYNOPSIS
admin.sh 
.I [options]
.B -l

admin.sh
.I [options] <module>
.B start|stop|status

admin.sh
.I [options] <module>
.B restart|force-reload

admin.sh
.I [options] <module>
.B try-restart

.SH DESCRIPTION
.B admin.sh
is like 
.I LSB (Linux Standard Base) init scripts
but on an application level. 
It can manage a set of modules with launching, stopping or show status of running modules.

With this script you can manage easily an application using multiples modules.

.SH OPTIONS
.TP 2
-M <directory>
indicates the path of the modules files (see MODULES).
default : admin-modules

.TP
-E <file>
indicates the path of the environment file (see MODULES).
default: 
.I none

.TP
-l
: show the list of modules.

.TP
-A nosys
action on all modules without
.B sys 
prefix.
Use it instead <module>.

.TP
-A allsys
action on all modules.
Use it instead <module>.

.TP
-v
show this 
.B admin.sh 
script's version.

.TP
-?
show the help message.

.SH COMMANDS
.TP 2
start
: start a module.

.TP
stop
: stop the module.

.TP
status
: show the status of the module.

.TP
restart (or force-reload)
: stop the module (if running) after restart it.
.I force-reload is for LSB compatibility.

.TP
try-restart
: restart only if the module is running

.SH MODULES
A module is a file describing how to start, stop or get status of a component.
It's a script file with particular format (see below).
This file contains shell functions and description. 
An environment file can be used too for storing parameters or global functions.

.SS Environment file
It's an optional script launched on current shell (with 
.B . (dot) 
command). This file must be indicated with the 
.B -E 
option.

.SS Filename
This module's file must be in a directory (by default 
.I admin-modules
) with one of this format :
.I <number>_<name>
or
.I <number>_sys_<name>
were 
.TP 2
<number>
is a number. It indicates the order to launch this module when 
.B -A 
option is used. When stopping, the order is reversed.

.TP
<name>
is the name you want.
.TP
sys
is used for indicated a system module.

.SS System modules
A system module represents a component used globally on the system. Like 
.I ldap server
or
.I dns server 
that is when stopping this component has an impact on the machine and on the other applications.

.SS Format of the file
The file must contain description of the module (comment with NNNA) and 3 shell functions:
.TP 1
fn_status
.TP
fn_start
.TP
fn_stop.



Below, a template for the file:

 #!/bin/sh

 # ################################################# #
 # NNNA description describe here the component      #
 # NNNA author      you                              #
 # NNNA version     version of the script            #
 # ################################################# #

 fn_status()
 {
  #get the status of the component (like on System V)
  status=0 #0 the component is running
  status=1 #1 the component is dead but PID file exists
  status=2 #2 the component is dead but lock file exists
  status=3 #3 the component is stopped
  return $status
 }

 fn_start()
 {
  #launch the component
  return 0 #the component is started
  #other exit status = failed 
 }

 fn_stop()
 {
  #stop the component
  return 0 #the component is stopped
  #other exit status = failed 
 }


.SH EXAMPLE
For instance if your application is composed by a website and database, you can create two module : 
.TP 2
one for the website
.TP
another for the database



.SS Website
The website is hosted in a virtualhost on a shared Apache server. 
So, the Apache is a system module.
We create the file 
.B admin-modules/20_sys_apache.
Below the content
 #!/bin/sh

 # ################################################# #
 # NNNA description apache web server                #
 # NNNA author      Example' author                   #
 # NNNA version     version 1.0                      #
 # ################################################# #

 fn_status()
 {
  service apache2 status
  return $?
 }

 fn_start()
 {
  service apache2 start
  return $?
 }

 fn_stop()
 {
  service apache2 stop
  return $?
 }

.SS Database
The database instance is launched on standalone but must be launch before Apache.
We create the file
.B admin-modules/10_database.
Below the content
 #!/bin/sh
 
 # ################################################# #
 # NNNA description database of the website          #
 # NNNA author      Example' author                  #
 # NNNA version     version 1.0                      #
 # ################################################# # 

 PG_CTL=/usr/lib/postgresql/9.1/bin/pg_ctl
 
 fn_status()
 {
  su - postgres -c "$PG_CTL status -D /var/nnnadminexample/mydatabase"
  case $? in  #transform the pg_ctl exit status on system V
  '0') return 0;;
  '1') return 3;;
  *) return 4;;
  esac
 }
 
 fn_start()
 {
  su - postgres -c "$PG_CTL start -D /var/nnnadminexample/mydatabase"
  return $?
 }

 fn_stop()
 {
  su - postgres -c "$PG_CTL stop  -D /var/nnnadminexample/mydatabase"
  return $?
 }

.SS Launching database only
admin.sh database start

.SS Showing status for all
admin.sh -A allsys status

.SS Stopping no system modules
admin.sh -A nosys stop

.SS Restart Apache
admin.sh apache restart

.SH AUTHOR
3Zen

.SH SEE ALSO
.BR backup.sh(1),
.BR check.sh(1),
.BR launch.sh(1)
